The cache becomes a cloneable `Cache` handle (built from CacheConfig) whose
clone shares the same tiers, so one cache can back both a track's TrackProducer
and its TrackConsumer. Add TrackConsumer::with_cache and spell out the consumer
fetch semantics: fetch_group / get_group resolve from the cache first (RAM sync,
disk/remote after a ranged read), miss falls through to the wire and populates
the cache, and live subscribe groups populate it too. A cache-backed consumer
with no upstream answers FETCH straight from storage (the archive serve path).
Inserts dedup by sequence so sharing one cache across both sides is safe.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Add the moq_net::cache module: a per-track bounded group cache with the
produce/consume split. cache::Config::produce() yields a cache::Producer (write
half, not Clone) and Producer::consume() a cache::Consumer (read half, Clone),
sharing one store so a cache backs both a track's producer and consumer.

Eviction is a high/low watermark, not an LRU: an insert over the high watermark
drains the oldest groups down to the low watermark and returns them as one Batch
(the caller persists it to the next tier), which is what lets a group-per-frame
audio track avoid one tiny object per group. Bounds are per-track on bytes and
duration (media-timestamp span), the latest group is never evicted, and inserts
dedup by sequence so sharing one cache across both endpoints is safe.

14 unit tests cover get/miss, dedup, byte and duration watermarks, batch
contents, always-keep-latest, hysteresis within the band, unbounded and
min-unset edges, and out-of-order inserts.

Disk/remote tiers and the TrackProducer/TrackConsumer with_cache wiring remain
design; CACHE.md is reconciled to the implemented names and marks what is built.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

The module-level //! doc used intra-doc links to same-module items (Batch,
Producer, Consumer), which rustdoc cannot resolve from an inner module doc
(even with self:: paths), failing `cargo doc -D warnings` in CI. Use plain
code spans there; item-level links are unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Add cache::segment: the on-disk byte format for the cache's disk/remote tiers
and the rollup that compacts small segments into one larger object.

A segment is one band of groups (a Batch) serialized as group blobs back to
back, a footer offset table, then a fixed 8-byte trailer (footer length +
magic). The trailer being last and fixed-size lets a reader fetch it with one
tail-ranged GET, parse the footer, then fetch just the byte range of the wanted
group. Each blob is self-delimiting (frame count, then length-prefixed frames
carrying their optional media timestamp). Timestamps store raw value+scale, so
a non-micro timescale (e.g. 90kHz video) round-trips exactly. Reuses the QUIC
VarInt codec. rollup copies group blobs verbatim and rewrites offsets, so it is
lossless and does not re-encode frames.

To serialize losslessly, cache::Group now carries per-frame timestamps
(cache::Frame { timestamp, payload }) with ts_first()/ts_last() derived for the
duration bound; the RAM tier and its tests are updated accordingly. The module
becomes a directory (cache/mod.rs + cache/segment.rs).

12 new segment tests (batch/single round-trip, footer summary, lossless
non-micro scale, mixed/absent timestamps, empty group and empty batch, missing
sequence, bad magic, truncation, rollup concat + offsets + single-segment +
corrupt-input). All 415 moq-net lib tests pass; clippy and rustdoc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Add cache::index: the storage-agnostic layer that ties the segment format and
rollup into serving across tiers. It maps each group sequence to a Location
(tier + segment + byte range), so a fetch is "locate, then ranged-read that
segment." It tracks per-tier byte and duration totals, and drives promotion:
Index::promotion picks the oldest disk segments once the disk tier is over its
high watermark (draining to the low watermark, oldest first), and
Index::apply_promotion registers the rolled-up remote segment, repoints those
sequences at the remote tier, and drops the promoted disk segments.

The index holds only metadata, never group bytes, so it is the part that stays
in memory while bytes live on disk/remote. Add segment::group_from_blob, the
ranged-read decode entry point (decode one group from just its blob bytes), and
Segment::byte_len for tier accounting. The remaining object_store put/get_range
glue is a thin layer over these decisions.

7 index tests including an end-to-end check: encode segments, locate, ranged-
read via group_from_blob, then promote (rollup) and confirm every group still
decodes identically through the remote segment. Full moq-net suite 422 pass;
clippy and rustdoc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

The cloned_ref_to_slice_refs lint (rust 1.96) flags &[x.clone()]; use
std::slice::from_ref(&x) instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Wrap the long rollup line flagged by cargo fmt --check in CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Add cache::Group::read (async: drain a live GroupConsumer into a cache::Group,
reading each frame's payload and timestamp, resolving on group finish) and
cache::Group::produce (sync: rebuild a live GroupConsumer from a cache::Group,
validating frame timestamps against the track timescale). These are the bridge
the TrackProducer populate path and TrackConsumer serve path both use.

Two async round-trip tests (timed and untimed groups): live -> cache -> live ->
cache preserves sequence, payloads, and per-frame timestamps.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

TrackProducer::with_cache(cache::Producer) spawns an internal subscriber that
drains each finished group into the cache (producer fills). The subscription
keeps the track active while caching, independent of downstream demand.

TrackConsumer::with_cache(cache::Consumer) attaches a read-through cache:
get_group and fetch_group resolve from it on a live-state miss, rebuilding the
group at the track's timescale. fetch_group serves from the cache before
failing with NotFound or waiting on a TrackDynamic, via a pre-resolved branch
added to TrackFetch. So a consumer sharing the producer's cache supports fetch
without a wire round-trip.

Three tests: producer fills the cache and a shared reader sees the group;
get_group and fetch_group fall through to the cache and read back byte-for-byte.
Full moq-net suite 427 pass; clippy and rustdoc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Add the cache-tiered feature (off by default so RAM-only and wasm builds stay
dependency-free) and cache::store::Store, the object_store glue over the index:

- flush(batch): segment::encode the band, put it as one disk segment, record it
  in the index, then compact.
- get(seq): index.locate -> get_range the blob -> segment::group_from_blob.
- compact(): when the disk tier is over its bounds, read the oldest segments,
  segment::rollup them into one remote object, apply_promotion to repoint the
  index, and delete the disk objects; with no remote tier, evict them instead.

object_store is added default-features = false (core + memory + local fs, no
cloud SDKs). Add Index::evict for the no-remote eviction path.

5 tests against object_store::memory::InMemory: flush/get round-trip, promotion
to remote preserving all groups, eviction of the oldest without a remote, plus
a non-gated Index::evict unit test. Default suite 428 pass; with cache-tiered,
39 cache tests pass; clippy/rustdoc/fmt and --no-default-features clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

…nning-r7xgqp

# Conflicts:
#	Cargo.toml

Correctness:
- index::promotion never selects the single newest disk segment (mirrors the
  RAM "keep latest" rule). Without it, an unset low watermark drained the whole
  disk tier on one over-max trip -> data loss of recent groups on the no-remote
  eviction path.
- store crash-consistency: write the object before mutating the index. flush
  puts the disk segment under index.next_id() then add()s; compact uploads the
  rolled remote object before apply_promotion. A failed put/upload now leaves
  the index (and the disk segments it points at) intact instead of stranding
  sequences on a nonexistent object. Added Index::next_id() for the peek.
- store::get guards offset+length with checked_add (a corrupt footer could
  overflow u64 and produce a bad range), matching segment::blob.
- TrackConsumer::fetch_group rebuilds the cached group synchronously and treats
  a rebuild error as a miss (falling through to the live path), consistent with
  get_group. Previously a produce() error (e.g. timescale mismatch on a
  not-yet-accepted wire consumer) surfaced as a hard fetch failure. TrackFetch
  now holds the rebuilt GroupConsumer.

Cleanup:
- store_of expects a configured remote tier for a remote location instead of
  silently falling back to disk.
- index is internal orchestration: gate it behind cache-tiered (its only user
  is the gated store) and drop it from the public surface; segment::GroupEntry
  gets #[non_exhaustive].
- Document the two with_cache caveats the review surfaced (the internal
  subscriber disables demand teardown; a stalled group head-of-line-blocks
  caching of later finished groups).

Default suite 427 pass; with cache-tiered, 39 cache tests pass. clippy (both
feature sets), rustdoc, and fmt clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

cache::Config gains an optional `disk: Disk` tier (native-only): an object_store,
a key prefix, retention bounds, and an optional remote rollup store. Build with
Disk::new(...).with_remote(...).

Config::produce() now spawns a background task (when a disk tier is set) that
drains RAM-evicted bands through an mpsc channel into a shared store::Store
(behind a tokio RwLock so reads run concurrently with the flusher).
Producer::insert hands each evicted band to that task instead of returning it.
Consumer gains an async fetch() that reads RAM, then disk, then remote (get()
stays a sync RAM-only lookup). State now holds the RAM Bounds directly rather
than the whole Config.

So a cache with a disk tier now actually spills to and serves from disk/remote
with no extra wiring, on native; wasm builds drop the tier fields entirely.

Test: a Producer with an InMemory disk tier, insert past the RAM watermark, and
the consumer fetches the evicted group back from disk. Default suite 439 pass;
clippy/rustdoc/fmt and --no-default-features clean. CACHE.md updated to match.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

cargo-deny flagged RUSTSEC-2026-0185, a remote memory-exhaustion vulnerability
in quinn-proto 0.11.14 (unbounded out-of-order stream reassembly). Pulled in
transitively via quinn -> web-transport-quinn -> moq-native. 0.11.15 is the fix
release and a drop-in patch (same dependency tree), so this is a surgical lockfile
bump. Unrelated to the cache feature; it just lands here to get the PR's CI green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo

Two review follow-ups:

- Media-time gate now drops stale arrivals outright instead of archiving them.
  A group evicted by the media gate (media already past the window the instant it
  lands: a startup burst or a lagging publisher) is not spilled to the cache, and
  if it is still open it is aborted (Error::Old) so a producer still downloading a
  group too stale to keep stops wasting bandwidth and releases its buffers. Only a
  finished group aged out by the wall-clock gate is archived. A finished
  media-stale group (e.g. a deliberately fetched old group) is dropped without
  aborting, so a consumer still reading it is unaffected.

- compact no longer holds the store lock across the remote upload. Split into
  plan_compaction (locked: snapshot the rollup, reading disk bytes and building the
  rolled object) -> Rollup::upload (unlocked: the slow remote put) -> apply_compaction
  (locked: repoint the index, delete disk). The rolled object is refcounted Bytes,
  so the snapshot is cheap, and the disk segments stay indexed until apply, so a
  concurrent fetch is unaffected. Store::compact keeps the all-in-one path for tests.
  The flush task binds each phase to its own statement so the lock guard drops at the
  `;`; holding it across the match also self-deadlocked the re-entrant write() in apply.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R8gBynFAeeVnxuffr4ZKUo